/*
 * =====================================================================================
 *
 *       Filename:  filecaching.h
 *
 *    Description:  Definition of functions and structures for file caching
 *
 *        Version:  1.0
 *        Created:  28/10/2010 15:10:23
 *       Revision:  none
 *       Compiler:  gcc
 *
 *         Author:  François Hissel (), francois.hissel@developpement-durable.gouv.fr
 *        Company:  CETMEF
 *
 * =====================================================================================
 */

#ifndef  FILECACHING_INC
#define  FILECACHING_INC

#ifdef TRACE
#include	<stdio.h>
#endif
#include	"pathutils.h"

extern int cache_id;	//!< Current ID of local cache file

/**
 * \brief Association between a virtual handle and a file on the remote system
 *
 * This structure holds the association between a private handle (as known by the virtual filesystem) and a virtual file or folder on the remote system. It also contains the real handle of the temporary file used to cache IO operations on the virtual file.
 */
typedef struct FileHandle {
	long handle;	//!< Internal handle of the file, and also the handle of the corresponding file on the local system if it is still open, 0 if the virtual entity is a folder
	int id;	//!< For a file, refers to its identification number, from which the name of the local file is computed. This field must be the same as the one with the same name in the Folder structure
	char *path;	//!< Virtual path of the file on the web server
	Folder *folder;	//!< Folder structure associated with the file handle
} FileHandle;

/**
 * \brief List of file handles
 *
 * This structure holds a chained list of FileHandle structures. It is used to store the handles of the open files on the virtual filesystem.
 */
typedef struct FileList {
	FileHandle file;	//!< Virtual handle of the file
	struct FileList *next;	//!< Next element in the list, 0 if the element is the last one of the list
} FileList;

/**
 * \brief Create a new FileList element
 *
 * This function creates a new FileList element and initializes its member fields
 * \param handle Handle of the element
 * \param path Virtual path of the element
 * \param folder Pointer to the folder structure
 * \return Pointer to the new FileList element
 */
FileList *create_file_list(long handle,const char *path,Folder *folder);

/**
 * \brief Get the temporary file name associated with a FileHandle structure
 *
 * This function returns a unique temporary file name which can be used by a FileHandle structure
 * \param id ID of the local file associated with the FileHandle
 * \param name Previously allocated string with a sufficient size which will hold the file name after the end of the function
 */
void get_local_file_name(int id,char *name);

/**
 * \brief Release a FileList chained list
 *
 * This function releases the memory allocated for a chained list of FileHandle elements.
 * \param list FileList structure to be released
 */
void free_file_list(FileList *list);

/**
 * \brief Get the FileList element associated with a handle
 *
 * This function searches in the FileList the element which has the same handle as the argument. If this element is found, it is returned. Otherwise, the function returns 0.
 * \param list List of FileHandle
 * \param handle Handle for which the function will look
 * \return FileList element with the same handle, or 0 if none is found
 */
FileList *find_handle(FileList *list,long handle);

/**
 * \brief Get the FileList element associated with a file name
 *
 * This function searches in the FileList list the element which has the same name as the argument. If this element is found, it is returned. Otherwise, the function returns 0.
 * \param list List of FileHandle
 * \param name Name of the file to look for, including its path
 * \return FileList element with the same handle, or 0 if none is found
 */
FileList *find_name(FileList *list,const char *name);

/**
 * \brief Delete a FileList element identified by its pointer
 *
 * This function erases a FileList element from the list. The element is identified by its pointer. If it is found, the function returns 0. Otherwise, it returns -1.
 * \param list Pointer to the list. A pointer is necessary here because the list has to be modified if the deleted element is the first one
 * \param pointer Pointer to the element to be deleted
 * \return 0 if the element was found and deleted, -1 otherwise
 */
int free_handle(FileList **list,FileList *pointer);

#ifdef TRACE
/**
 * \brief Print a list of handles
 *
 * This function prints the list of handle on the output stream. It is useful only for debugging purposes.
 * \param file File stream
 * \param list List of handles to be printed
 */
void print_file_list(FILE *file,FileList *list);
#endif

#endif   /* ----- #ifndef FILECACHING_INC  ----- */
